home *** CD-ROM | disk | FTP | other *** search
/ H4CK3R 14 / hacker14.iso / programacao / visual / perl.exe / {app} / Library / YAPE / Extra / YAPE.pm
Encoding:
Perl POD Document  |  2001-02-05  |  4.4 KB  |  180 lines
  1. =head1 NAME
  2.  
  3. YAPE - Yet Another Parser/Extractor
  4.  
  5. =head1 SYNOPSIS
  6.  
  7.   use YAPE::Something;
  8.   
  9.   my $parser = YAPE::Something->new(...);
  10.   
  11.   # do magical and wondrous things
  12.  
  13. =head1 DESCRIPTION
  14.  
  15. The C<YAPE> hierarchy of modules is an attempt at a unified means of parsing
  16. and extracting content.  It attempts to maintain a generic interface, to
  17. promote simplicity and reusability.  The API is powerful, yet simple.  The
  18. modules do tokenization (which can be intercepted) and build trees, so that
  19. extraction of specific nodes is doable.
  20.  
  21. =head2 Wishful Thinking
  22.  
  23. This discipline of parsing/extracting is here in hopes of creating an API that
  24. allows you to parse some language -- C, for instance -- and fiddle with it.  Here
  25. are a couple examples of what C<YAPE::C> might be capable of.
  26.  
  27. =head3 Code Filtering
  28.  
  29. First, we create a C<YAPE::C> object:
  30.  
  31.   use YAPE::C;
  32.   
  33.   open ORIG, "+<myprog.c"
  34.     or die "can't open myprog.c for r/w: $!";
  35.   my $code;
  36.   { local $/; $code = <ORIG>; }
  37.   
  38.   seek ORIG, 0, 0;
  39.   truncate ORIG, 0;
  40.   
  41.   my $parser = YAPE::C->new($code);
  42.  
  43. Now, we go through the code it parses, chunk by chunk (tokenizing):
  44.  
  45.   while (my $chunk = $parser->next) {
  46.     # turn 'foo.bar = 2 * 3;'
  47.     # into 'foo.bar = filter(2 * 3);'
  48.     if (
  49.       $chunk->type eq 'assign' and
  50.       $chunk->lhs->fullstring eq 'foo.bar'
  51.     ) {
  52.       my $func = YAPE::C::function('filter');
  53.       $func->args($chunk->rhs);
  54.       $chunk->rhs($func);
  55.     }
  56.   }
  57.  
  58. Now, we print the modified code:
  59.  
  60.   print ORIG $parser->fullstring;
  61.   
  62.   close ORIG;
  63.  
  64. In an ideal world, that would safely place the C<filter()> function around the
  65. arguments of all assignments to C<foo.bar>.
  66.  
  67. =head3 Code Creation
  68.  
  69. A statement like C<alpha.beta.gamma = 2 * 3;> would be represented as
  70.  
  71.   my $assign = YAPE::C::statement->new(
  72.     YAPE::C::assign->new(
  73.       YAPE::C::struct->new(
  74.         'alpha',
  75.           YAPE::C::struct->new(
  76.           'beta',
  77.           YAPE::C::attr->new('gamma'),
  78.         ),
  79.       ),
  80.       YAPE::C::op->new(
  81.         '*',
  82.         YAPE::C::num->new(2),
  83.         YAPE::C::num->new(3),
  84.       ),
  85.     )
  86.   );
  87.  
  88. The internal tree for this would look like
  89.  
  90.   {
  91.     TYPE => 'statement',
  92.     CONTENT => [
  93.       {
  94.         TYPE => 'assign',
  95.         
  96.         LHS => {
  97.           TYPE => 'struct',
  98.           VAL => 'alpha',
  99.           ATTR => {
  100.             TYPE => 'struct',
  101.             VAL = 'beta',
  102.             ATTR => {
  103.               TYPE => 'attr',
  104.               VAL => 'gamma',
  105.             },
  106.           },
  107.         },
  108.         
  109.         RHS => {
  110.           TYPE => 'op',
  111.           OP => '*',
  112.           TERMS => [
  113.             {
  114.               TYPE => 'num',
  115.               VAL => 2,
  116.             },
  117.             {
  118.               TYPE => 'num',
  119.               VAL => 3,
  120.             },
  121.           ],
  122.         },
  123.       },
  124.     ],
  125.   }
  126.  
  127. =head3 Code Extraction
  128.  
  129. If you wanted to extract all the comments from a C program, you would do so in
  130. the following manner:
  131.  
  132.   my $extractor = $parser->extract(-COMMENT);
  133.   my @comments;
  134.   while (my $chunk = $extractor->()) {
  135.     push @comments, $chunk;
  136.   }
  137.  
  138. Or, if you wanted to find all the C<if>-statements in a program, you might do:
  139.  
  140.   my $extractor = $parser->extract(if_stmt => []);
  141.   my @if_stmts;
  142.   while (my $chunk = $extractor->()) {
  143.     push @if_stmts, $chunk;
  144.   }
  145.  
  146. =head2 Reality Check
  147.  
  148. Obviously, C<YAPE::C> would have to do a lot of work to offer the potentially
  149. massive requests sent to it ("give me all function calls that use the variable
  150. C<foo.bar> in them"); so this module might be a long way off.
  151.  
  152. But it's not impossible, if the C code is parsed properly.
  153.  
  154. =head1 DEVELOPMENT
  155.  
  156. Jeff C<japhy> Pinyan is the front-man for the C<YAPE> hierarchy of modules; all
  157. requests/candidates for a new C<YAPE> module should be sent through him.  His
  158. contact information is at the bottom of this document.  The C<YAPE> web site is
  159. at F<http://www.pobox.com/~japhy/YAPE/>.
  160.  
  161. All C<YAPE> modules are designed to have the same general exterior API.  This
  162. is like the C<DBI> approach.  Jeff intends to keep things this way.  If a new
  163. feature gets added to C<YAPE::Foo>, that feature should be added (even if only
  164. as a no-op if not applicable) to all other C<YAPE> modules.  This is only true
  165. for the parser's API; individual elements (such as HTML tags, or C operators,
  166. or regular expression nodes) can behave in their own idiom.
  167.  
  168. =head1 AUTHOR
  169.  
  170.   Jeff "japhy" Pinyan
  171.   CPAN ID: PINYAN
  172.   japhy@pobox.com
  173.   http://www.pobox.com/~japhy/
  174.  
  175. =head1 SEE ALSO
  176.  
  177. The C<YAPE> module you're looking for.
  178.  
  179. =cut
  180.